home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / dmake.doc < prev    next >
Text File  |  1994-02-13  |  9KB  |  240 lines
  1.  
  2.                 DMAKE V 2.0
  3.  
  4.     Matthew Dillon        dillon@Overload.Berkeley.CA.US
  5.     891 Regal Rd.        uunet.uu.net!overload!dillon
  6.     Berkeley, Ca. 94708
  7.     USA
  8.  
  9.  
  10.     DMake   -    Dillon's MAKE utility (NOT Make or Lmk compatible.. better)
  11.  
  12.     The idea with DMake is to provide a powerful make utility through
  13.     general features rather than specialized hacks.  DMake is governed
  14.     by a few simple rules that can be combined into incredibly powerful
  15.     operations.
  16.  
  17.     Generally you simply run 'DMake' and have a list of dependancies in
  18.     your 'DMakefile' which DMake then executes.  The DMakefile may contain
  19.     three different kinds of lines:
  20.  
  21.     (1) COMMENTS -- Any line beginning with a '#' is a comment and ignored
  22.  
  23.     # This DMakefile generates an executable for fubar, the compiler
  24.     # options are as follows ...
  25.  
  26.     (2) ASSIGNMENTS -- Any line of the form <SYMBOL> = ...  is considered
  27.     an assignment.    Any variable references from within the assignment will
  28.     be resolved immediately.
  29.  
  30.     CFLAGS= -r
  31.     SRCS= x.c y.c z.c
  32.  
  33.     (3) DEPENDANCIES: -- A line containing a list of symbols, a colon, and
  34.     more symbols is assumed to be a dependancy.  Note that you cannot
  35.     have a raw filename with a colon in it as that confuses DMake.
  36.     Instead, use an ASSIGNMENT variable.
  37.  
  38.     Following the dependancy line is zero or more command lines --
  39.     commands to run to resolve the dependancy, terminated with a
  40.     blank line.
  41.  
  42.     NOTE: not only is a zero-command dependancy allowed, it is necessary in
  43.     some cases.  A particular destination may have only ONE command list so
  44.     if you have something like 'a.o : a.c' with a command list to compile
  45.     the source into an object you can also have another dependancy such as
  46.     'a.o : defs.h' which would NOT have any associated command list.
  47.  
  48.  
  49.     dst1 ... dstN : src1 ... srcN
  50.     command1
  51.     command2  ...
  52.  
  53.     dst1 ... dstN : src1 ... srcN
  54.     command1
  55.     command2  ...
  56.  
  57.     Finally, note that a dst* or src* symbol does not need to be a
  58.     filename.  It is perfectly valid to make up dummy names which are then
  59.     used as the lhs of a dependancy that collects other dependancies
  60.     together.
  61.  
  62.                   DEPENDANCIES
  63.  
  64.     When declaring dependancies you may use four different forms.  The
  65.     first form is to have a single destination and several sources.  This
  66.     is intreted to mean that ALL the sources must be resolved before the
  67.     single destination can be resolved via the command list for the
  68.     dependancy.  The special variable, %(left), is set to the <dst> symbol
  69.     and the special variable %(right) is set to ALL of the <src*> symbols
  70.  
  71.     For example, this form would be used to indicate that an executable
  72.     depends on all the objects being resolved before you can run the link.
  73.  
  74.     (1) dst : src1 src2 src3 ... srcN
  75.  
  76.     The second form is the most useful in that it allows you to specify
  77.     multiple 1 : 1 dependancies.  Thus, you can specify, for example, that
  78.     each object file depends on its source file counterpart for ALL the
  79.     files in your project on a single line and have a single command list
  80.     representing what to do (to compile a source file into an object, say).
  81.  
  82.     In this case %(left) and %(right) are set to each dst* : src* pair
  83.     individually and the command list is run for any individual pair that
  84.     is out of date.
  85.  
  86.     (2) dst1 dst2 dst3 ... dstN : src1 src2 src3 ... srcN
  87.  
  88.     The next form may be used to specify that many files depend on one file
  89.     being resolved.  An example of usage would be to make all the object
  90.     files depend on one header file.  The command list, if any, is run for
  91.     each dst* : src pair with %(left) set to the current dst* and %(right)
  92.     set to the single source.
  93.  
  94.     (3) dst1 dst2 dst3 ... dstN : src
  95.  
  96.     The last form is esoteric but sometimes useful.  EACH dst* on the left
  97.     hand side depends on the entire right hand side.  You can have an
  98.     arbitrary number of symbols on either side.  %(left) will be set to a
  99.     particular DST while %(right) will be set to all of the SRCs.
  100.  
  101.     for example, you could specify $(OBJS) :: $(HDRS)  -- make all objects
  102.     depend on all headers causing a recompile to occur if any header is
  103.     modified.
  104.  
  105.     (4) dst1 dst2 dst3 ... dstN :: src1 src2 ... srcI
  106.  
  107.  
  108.             WILDCARDED FILE LIST REPLACEMENT
  109.                 VARIABLE ACCESS
  110.  
  111.     DMake's most powerful feature is an easy to use file list replacement
  112.     through options in a variable specification.  You may insert the
  113.     contents of any variable using the form:
  114.  
  115.     $(SYMBOL)
  116.  
  117.     Furthermore, you can make modifications to the contents of the variable
  118.     on the fly using:
  119.  
  120.     $(SYMBOL:wildcard)              only those files which match <wildcard>
  121.     $(SYMBOL:wildcard:wildcard)     matching files and also do a conversion
  122.  
  123.     Simple */? wildcarding is used.  A wildcard may contain a colon or
  124.     other punctuation but if it does you MUST surround it with quotes.    Here
  125.     is a quick example:
  126.  
  127.     SRCS= a.c b.c c.c d.c xx.a
  128.     OBJS= $(SRCS:*.c:"dtmp:%1.o")
  129.  
  130.     all:
  131.         echo $(OBJS)
  132.  
  133.     (the result is 'dtmp:a.o dtmp:b.o dtmp:c.o dtmp:d.o')
  134.  
  135.     The first wildcard specification restricts which files from the list
  136.     are to be taken -- 'xx.a' was ignored, as you can see.  Each '*' or '?'
  137.     in the first wildcard specification corresponds to %N specifications
  138.     in the second wildcard specification.  You can prepend, insert, or
  139.     append text and freely mix or ignore items matched to create your
  140.     destination file list.
  141.  
  142.     This capability allows you to specify your source files EXACTLY ONCE
  143.     in the DMakefile and then use the file munging capability to convert
  144.     them to the object file list, etc...
  145.  
  146.     You can embed variables within variables as with the following example
  147.     (note that this time xx.a is included):
  148.  
  149.     OD= dtmp:fubar/
  150.     SRCS= a.c b.c c.c d.c xx.a
  151.     OBJS= $(SRCS:*.?:"$(OD)%1.o")
  152.  
  153.     all:
  154.         echo $(OBJS)
  155.  
  156.  
  157.     (the result is: 'dtmp:fubar/a.o dtmp:fubar/b.o dtmp:fubar/c.o
  158.     dtmp:fubar/d.o dtmp:fubar/xx.o')
  159.  
  160.     As a side note, you may also specify '?' and '*' in the destination
  161.     wildcard.  These are considered dummies and are equivalent to %N where
  162.     N is incremented from 1..9 for each '?' or '*' encountered.
  163.  
  164.     You can use the capability anywhere in the DMakefile.  Another common
  165.     thing to do is restrict your link line to include only the object files
  166.     and skip the headers:
  167.  
  168.     $(EXE) : $(PROTOS) $(OBJS) $(HDRS)
  169.         dcc %(right:*.o) -o %(left)
  170.  
  171.                 ENVIROMENT VARIABLES
  172.  
  173.     2.0 local variables and 1.3/2.0 ENV: variables are fully accessible.
  174.     Under 2.0 you can also modify local variables on the fly.
  175.     DMake-specific variables override 2.0 local variables overide ENV:
  176.     variables.
  177.  
  178.     Under 2.0, any command containing '<', '>', '`', or '|', or is an
  179.     alias, will be run with System().  Thus, such commands may not be used
  180.     to modify local variables or the local enviroment.    Also, such commands
  181.     cannot be ^C'd due to the way AmigaDOS works.
  182.  
  183.               LINE CONTINUATION AND ESCAPES
  184.  
  185.     Any line may be continued by terminating it with a backslash '\'.  It
  186.     is possible to escape the special characters '$' and '%' by doubling
  187.     them though this is only necessary if an open-parenthesis follows the
  188.     '$' or '%' and you do not want it interpreted as a variable.
  189.  
  190.     It is possible to escape ':' and other special characters by assigning
  191.     them (or a string containing them) to a variable
  192.  
  193.                 COMMAND SHELL
  194.  
  195.     Under 2.0 commands that do not contain any sort of redirection are run
  196.     with RunCommand().  If a command is an alias or there is some sort of
  197.     redirection in the arguments it will be run with System().
  198.  
  199.     Under 1.3 everything is run with Execute()
  200.  
  201.              EXTREMELY ADVANCED CAPABILITIES
  202.  
  203.     Now, you may have noted earlier that I said you could not have any
  204.     givem left-hand-side with more then one command list.  Take, for
  205.     example:
  206.  
  207.     a.o : a.c
  208.         dcc %(right) -o %(left)
  209.  
  210.     a.o : defs.h
  211.         **** illegal to put command list here ****
  212.  
  213.     Actually, it isn't illegal.  When DMake encounters a dependancy without
  214.     a command list it will automatically 'force' the next higher level
  215.     dependancy of the same left-hand-side.  Therefore if you do not have a
  216.     command list for the lower level left-hand-side things work as you
  217.     expect.  Note that this requires all such null dependancies to exist
  218.     AFTER the one that has the command list.
  219.  
  220.     If you do have two or more command lists for the same left-hand-side
  221.     they will run independant of each other according to their individual
  222.     right hand sides.  If several command lists apply then their order of
  223.     execution will be bottom-up
  224.  
  225.               EXISTANCE OF A FILE OR DIRECTORY
  226.  
  227.     Another advanced feature quite useful in fully automating the
  228.     compilation process is the ability to create a directory tree on
  229.     the fly.  That is, if you have a projects called 'fubar' and want
  230.     the objects to go into the directory DTMP:fubar/ you might want to
  231.     have a dependancy that creates DTMP:fubar if it does not already
  232.     exist.
  233.  
  234.     XX= dtmp:fubar
  235.  
  236.     $(XX) : $(XX)
  237.         makedir %(left)
  238.  
  239.  
  240.